home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Libraries / Graphic Elements 2 / LibHeaders / DispCtrl.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-06-26  |  8.2 KB  |  309 lines  |  [TEXT/MPS ]
  1. /*
  2.     DispCtrl.h
  3.     
  4.     Display Controller routines for Graphic Elements
  5.     
  6.     Copyright 1994 by Al Evans. All rights reserved.
  7.     
  8.     Version 1.5b1 release
  9.     
  10.     6/26/94
  11.  
  12. */
  13.  
  14. #ifndef DISPCTRL
  15. #define DISPCTRL
  16.  
  17. #include "Defs.h"
  18.  
  19.  
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23.  
  24.  
  25. //Creation of new GEWorld
  26.  
  27. /*
  28.     Returns pointer to a new GEWorld. This world covers the area of worldPort
  29.     specified by worldRect (in port coordinates), if scale is scaleOneToOne.
  30.     
  31.     Scale determines the interpretation of the position and size of worldRect 
  32.     within worldPort. Briefly, if a GEWorld has a certain position and size in
  33.     a GrafPort at scaleOneToOne, that GEWorld will have the same *relative* position
  34.     and size, if the horizontal and vertical dimensions of the GrafPort are halved,
  35.     at a scale of 0x00008000 (0.5 in fixed-point notation). 
  36.     
  37.     If it is not nil, worldColors
  38.     must be a handle to a color table appropriate for an 8-bit depth.
  39.     
  40. */
  41.  
  42. GEWorldPtr NewGEWorld(GrafPtr worldPort, Rect *worldRect, Fixed scale, CTabHandle worldColors);
  43.  
  44.  
  45. //Destruction of a GEWorld
  46.  
  47. /*
  48.     Disposes of a world and everything in it.
  49. */
  50.  
  51. void DisposeGEWorld(GEWorldPtr world);
  52.  
  53.  
  54. //Management of a GEWorld
  55.  
  56. /*
  57.     Set default loader function for world.  If no loader is specified when a new
  58.     Graphic Element is created, this function is used.
  59.     
  60.     In a newly-created world, this loader function is one which creates an offscreen
  61.     GWorld and loads one or more PICTS from an open resource fork into it.
  62. */
  63.  
  64. void SetDefaultLoadFunc(GEWorldPtr world, GraphicLoadFunc loader);
  65.  
  66. /*
  67.  
  68.     Activate or deactivate an individual world
  69. */
  70.  
  71. void ActivateWorld(GEWorldPtr world, Boolean turnItOn);
  72.  
  73. /*
  74.     Get and set projection rate
  75.     These are NOT very useful, but MAY improve performance in some situations on
  76.     slower machines.
  77. */
  78.  
  79. void SetProjectionRate(GEWorldPtr world, short newMSPerFrame);
  80.  
  81. short GetProjectionRate(GEWorldPtr world);
  82.  
  83. /*
  84.     Control GEWorld's timer
  85. */
  86.  
  87. void StartGETimer(GEWorldPtr world);
  88.  
  89. void StopGETimer(GEWorldPtr world);
  90.  
  91.  
  92. //Returns current time in world
  93. unsigned long CurrentGETime(GEWorldPtr world);
  94.  
  95. /*    Set the number of timer milliseconds that pass per "real"
  96.     millisecond. newRate is treated as a fixed-point number,
  97.     with a two-byte positive integer and a two-byte fraction,
  98.     such that a value of 0x00010000 will give a 1-to-1
  99.     correspondence between Graphic Elements "milliseconds"
  100.     and real milliseconds.
  101. */
  102.  
  103. void SetGETimerRate(GEWorldPtr world, unsigned long newRate);
  104.  
  105. //Returns current "rate" of timer in world
  106. unsigned long GetGETimerRate(GEWorldPtr world);
  107.  
  108. /*
  109.     Manipulate world coordinate system;
  110. */
  111.  
  112. /*
  113.     GetGEWorldFocus and SetGEWorldFocus should be used to "bracket" calls to
  114.     FocusOnGEWorld, in order to save and restore the previous focus.
  115. */
  116.  
  117. void GetGEWorldFocus(GEWorldPtr world, Point *currFocus);
  118. void SetGEWorldFocus(GEWorldPtr world, Point newFocus);
  119.  
  120. /*
  121.     Sets focus, i.e. coordinate system, to that of world
  122. */
  123.  
  124. void FocusOnGEWorld(GEWorldPtr world);
  125.  
  126. /*
  127.     Move an entire GEWorld relative to its window
  128. */
  129.  
  130. void MoveGEWorld(GEWorldPtr world, short dh, short dv);
  131. void MoveGEWorldTo(GEWorldPtr world, short h, short v);
  132.  
  133. /*
  134.     Scale a distance to the current world's worldScale.
  135.     This is necessary ONLY in creating new Graphic Elements,
  136.     for determining size and position within a world.
  137.     
  138.     Returns value * world->worldScale / 65536. If result is 0, returns
  139.     1 if value was positive, -1 if value was negative.
  140. */
  141.  
  142. short ScaleToWorld(GEWorldPtr world, short value);
  143.  
  144. /*
  145.     Generate a frame showing the world in its current state and display it on the screen.
  146.     Should be called frequently from application program, for example once each time
  147.     through the main event loop.
  148.     
  149.     If invalidate is true, the entire world is redrawn. Otherwise, only the changed
  150.     portions of world are updated.
  151. */
  152.  
  153. void DoWorldUpdate(GEWorldPtr world, Boolean invalidate);
  154.  
  155. /*
  156.     Call from event handler when mouse down in the window containing world.
  157.     Returns true if mouseDown was handled by a sensor, false otherwise.
  158. */
  159.  
  160. Boolean MouseDownInSensor(GEWorldPtr world, Point gMousePt);
  161.  
  162.  
  163. //Services provided by Display Controller for Graphic Elements
  164.  
  165. //Creation and destruction
  166.  
  167. /* 
  168.     Low-level element creation. This function allocates an element, calls its
  169.     GraphicLoadFunc proc (if any), and links it into the world. In itself, it 
  170.     initializes only the fields element->objectID and element->drawPlane (in
  171.     addition to those initialized by the GraphicLoadFunc).
  172.     
  173.     It is normally called only from a higher-level creation function.
  174. */
  175.  
  176. GrafElPtr NewGrafElement(GEWorldPtr world, OSType id, short plane, short elemSize,
  177.                             GraphicLoadFunc loadProc, short resStart, short nRsrcs);
  178.                             
  179. /*
  180.     Unlinks a graphic element from its world and disposes of it. Note: if the element is
  181.     part of a higher-level struct, i.e. if fields have been added, the application
  182.     program must provide a CleanupProc to dispose free any memory represented by pointers
  183.     stored in these fields (see SetCleanupProc below). DisposeGrafElement() will 
  184.     automatically call the CleanupProc of any element which has one.
  185. */
  186.  
  187. void DisposeGrafElement(GEWorldPtr world, OSType objectID);
  188.  
  189. /*
  190.     Set element's custom dispose proc.
  191. */
  192.  
  193. void SetCleanupProc(GEWorldPtr world, OSType elementID, CleanupProc elemCleanup);
  194.  
  195. //Access to Graphic Elements
  196.  
  197. /*
  198.     Returns individual element with ID objectID
  199. */
  200.  
  201. GrafElPtr FindElementByID(GEWorldPtr world, OSType objectID);
  202.  
  203. /*
  204.     Returns first element with drawPlane == plane. For collision checking, etc.
  205. */
  206.  
  207. GrafElPtr ElementsInPlane(GEWorldPtr world, short plane);
  208.  
  209. //Control of Graphic Elements
  210.  
  211. /*
  212.     ShowElement shows or hides a Graphic Element, depending on the value of showIt
  213. */
  214.  
  215. void ShowElement(GEWorldPtr world, OSType elementID, Boolean showIt);
  216.  
  217. /*
  218.     Move graphic elements
  219. */
  220.  
  221. void MoveElement(GEWorldPtr world, OSType elementID, short dh, short dv);
  222. void MoveElementTo(GEWorldPtr world, OSType elementID, short h, short v);
  223.  
  224. //Alternate interface: avoid lookup when GrafElPtr already available, for example
  225. //in Autochange procedures
  226.  
  227. void PtrMoveElement(GEWorldPtr world, GrafElPtr element, short dh, short dv);
  228.  
  229. //If doScale is false, PtrMoveElementTo considers h and v to be absolute pixel offsets
  230. //from the topLeft of the world
  231.  
  232. void PtrMoveElementTo(GEWorldPtr world, GrafElPtr element, short h, short v, Boolean doScale);
  233.  
  234. /*
  235.     Sets element's plane to newPlane
  236. */
  237.  
  238. void SetElementPlane(GEWorldPtr world, OSType elementID, short newPlane);
  239.  
  240. /*
  241.     Set element's autochange parameters. No autochange if changeProc == nil OR
  242.     changeIntrvl == 0
  243. */
  244.  
  245. void SetAutoChange(GEWorldPtr world, OSType elementID, AutoChangeProc changeProc,
  246.                         Ptr changeData, short changeIntrvl);
  247.                         
  248. /*
  249.     Set element's collision parameters. No collision if collisionPlane == 0
  250. */
  251.  
  252. void SetCollision(GEWorldPtr world, OSType elementID, CollisionProc collideProc, 
  253.                         short collidePlane);
  254.                         
  255. //Miscellaneous sensor services
  256.  
  257. //Add sensor to world's sensor list and make it active
  258. void AddSensorToList(GEWorldPtr world, OSType id, Rect *sensorRect);
  259.  
  260. //Remove sensor from world's sensor list and make it inactive
  261. void RemoveSensorFromList(GEWorldPtr world, OSType id);
  262.  
  263. //Set sensor's actionProc to newAction
  264. void SetSensorAction(GEWorldPtr world, OSType sensorID, SensorAction newAction);
  265.  
  266. //Get element's entry in world->sensorList, if any
  267. SListEntryPtr FindSensorListEntry(GEWorldPtr world, OSType sensorID);
  268.  
  269. /*
  270.     If anything in a world is changed from OUTSIDE the Graphic Elements system,
  271.     call this procedure with the affected rectangle.
  272. */
  273.  
  274. void ChangedRect(GEWorldPtr world, Rect *chgdRect);
  275.  
  276.  
  277. /*
  278.     GraphicLoadFunc which:
  279.     
  280.     1)    Searches to see if the required graphics are already available in this world, 
  281.         and copies their parameters if so,
  282.     2)     Otherwise, creates a new offscreen GWorld of an appropriate size, and
  283.         loads nResources PICTs from an open resource file into it, starting
  284.         at the PICT with resource number startResNum
  285.         
  286.     This is the default loaderFunc of a newly created GEWorld.
  287. */
  288.  
  289. pascal Boolean LoadPICTElement(GEWorldPtr world, GrafElPtr element,
  290.                                         short startResNum, short nResources);
  291.  
  292.  
  293. /*
  294.     GraphicLoadFunc which does nothing except initialize the appropriate fields.
  295.     For Graphic Elements which have no permanent offscreen representations, e.g.
  296.     strings or fills.
  297. */
  298.  
  299. pascal Boolean NoLoader(GEWorldPtr world, GrafElPtr element,
  300.                                         short startResNum, short nResources);
  301.  
  302.  
  303.  
  304. #ifdef __cplusplus
  305. }
  306. #endif
  307.  
  308.  
  309. #endif